CoolBar Control

A CoolBar control contains a collection of Band objects used to create a configurable toolbar that is associated with a form.

Remarks

A CoolBar control is a container control that typically contains two or more Bands which may be resized and rearranged by the user. Each Band contains a single Child control.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.


Bands Collection

A collection whose elements represent the bands on a CoolBar control. The Bands collection has a Count property which specifies the number of Band objects in the collection.

Syntax

object.Bands.Count

object.Bands(index)

The Bands collection syntax has these parts:

Part | Description
object | An object expression that evaluates to a CoolBar control.
index | An integer with a range from 1 to Bands.Count.

Remarks

The Bands collection enumerates the bands on a CoolBar control. For example, you might use it to change the BackColor property of all the bands on a control.

Note The Bands collection is not a member of the Visual Basic Collection class; you cannot create instances of it.


HeightChanged Event

Occurs when the Height of a CoolBar control changes.

Syntax

Private Sub object_HeightChanged([index As Integer], newheight As Single)

The HeightChanged event syntax has these parts:

Part | Description
object | An object expression that evaluates to a CoolBar control.
index | An integer that uniquely identifies a control if it’s in a control array.
newheight | Single-precision floating-point number specifying the new height of the control.

Remarks

The HeightChanged event occurs after the Resize event when the CoolBar height needs to change. This can occur when the user rearranges bands at run time, or when the height of one or more bands is changed programmatically.

This event is useful when the CoolBar is hosted by a container which is capable of suppressing changes. In such a case, reading the Height property during the Resize event may not be reliable, or the Resize event may be suppressed. The HeightChanged event allows you to add code to allow the CoolBar control to display properly.


Add Method (Bands Collection)

Adds a new Band object to the Bands collection.

Syntax

object.Add ([index As Long], [key As String], [caption As String], [image As Variant], [newrow As Boolean], [child As Object], [visible As Boolean])

The Add method syntax has these parts:

Part | Description
object | An object expression that evaluates to the Bands collection of a CoolBar control.
Index | Optional. A long integer that uniquely identifies a band within a Bands collection.
key | Optional. A unique string that identifies the Band object. Use this value to retrieve a specific Band object.
caption | Optional. A string containing the caption to be displayed on the band.
image | Optional. An integer or unique string specifying the ListImage object to use with object. The integer is the value of the Index property; the string is the value of the Key property.
newrow | Optional. Default = False. A Boolean expression specifying whether the new Band will be displayed in its own row.
child | Optional. An object reference specifying the control that will be a child of the band.
visible | Optional. Default = False. A Boolean expression specifying whether a new band will be visible at run time.


Band Object

A Band object represents an individual band in the Bands collection of the CoolBar control.

Remarks

A band is a region within a CoolBar control which can contain a single child control, caption, and image. Each Band may be moved and resized independently by the user at run time.

At design time, use the Insert Band and Remove Band buttons on the Bands tab in the Properties Page of the CoolBar control to insert and remove Band objects from the Bands collection. At run time, you can add and remove Band objects by using the Add and Remove methods of the Bands collection.


AllowVertical Property (Band Object)

Returns or sets a value indicating whether a band will be displayed when the CoolBar control’s orientation is set to vertical.

Syntax

object.AllowVertical [= boolean]

The AllowVertical property syntax has these parts:

Part | Description
object | An object expression that evaluates to a Band object in a CoolBar control.
boolean | A Boolean expression specifying whether the band is visible or hidden.

Settings

The settings for boolean are:

Setting | Description
True | (Default) Band is visible.
False | Band is hidden.

Remarks

To hide a band at startup when the Orientation is set to Vertical, set the AllowVertical property to False at design time. Setting this property in code enables you to hide and later redisplay a band at run time in response to a particular event.

Note When the Orientation property is set to vertical, both AllowVertical and Visible must be True for the band to be visible. If either is False, the band will not be visible.


BandBorders Property

Returns or sets a value indicating whether a CoolBar control displays narrow lines to separate the bands.

Syntax

object.BandBorders [= boolean]

The BandBorders property syntax has these parts:

Part | Description
object | An object expression that evaluates to a CoolBar control.
boolean | A Boolean expression specifying whether the band border is visible or hidden.

Settings

The settings for boolean are:

Setting | Description
True | (Default) Borders are visible.
False | Borders are hidden.

Remarks

To remove the borders between bands, set the BandBorders property to False at design time. Setting this property in code enables you to hide or display borders between bands at run time in response to a particular event. Setting this property affects all bands within a CoolBar control.

Note The BandBorders property has no effect on the outside border of the CoolBar itself. The CoolBar border is always displayed.


Bands Property

Returns a reference to a CoolBar control’s collection of Band objects.

Syntax

object.Bands

The object placeholder is an object expression that evaluates to a CoolBar control.

Remarks

You can manipulate Band objects using standard collection methods (for example, the Add and Remove methods). Each element in the collection can be accessed by its index, the value of the Index property, or by a unique key, the value of the Key property.


Caption Property (Band Object)

Returns or sets the caption that appears on a Band object in a CoolBar control.

Syntax

object.Caption [= string]

The Caption property syntax has these parts:

Part | Description
object | An object expression that evaluates to a Band in the Bands collection of a CoolBar control.
string | A string expression that evaluates to the text displayed as the caption.

Remarks

The caption will be displayed left-aligned in between the move handle and the child control. When a Band is displayed vertically, the width of the band is dependent upon the width of the caption.


Child Property (Band Object)

Sets or returns a reference to a child control in a Band object on a CoolBar control.

Syntax

Set object.Child = control

object.Child

The Child property syntax has these parts:

Part | Description
object | An object expression that evaluates to a Band in the Bands collection of a CoolBar control.
control | An expression that evaluates to a control in the Band object of a CoolBar control.

Remarks

You can set the Child property of a band at design time by selecting a control from the Child list on the Bands tab in the Properties Page of the CoolBar control. At run time you can retrieve the name of the control on a Band object by reading the Child property.

To assign a new child control to a band at run time, use the Set keyword. This will replace the existing control on the Band object.


EmbossHighlight Property

Sets or returns the highlight color for an image displayed on a CoolBar control.

Syntax

object.EmbossHighlight [= color]

The EmbossHighlight property syntax has these parts:

Part | Description
object | An object expression that evaluates to a CoolBar control.
color | A value or constant that determines the background or foreground colors of an object, as described in Settings.

Settings

Visual Basic uses the Microsoft Windows operating environment red-green-blue (RGB) color scheme. The settings for color are:

Setting | Description
Normal RGB colors | Colors specified by using the Color palette or by using the RGB or QBColor functions in code.
System default colors | Colors specified by system color constants listed in the Visual Basic (VB) object library in the Object Browser. The Windows operating environment substitutes the user's choices as specified in the Control Panel settings.

Remarks

The default setting for the EmbossHighlight property is the system default color specified by the constant vbButtonHighlight.

The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a number in this range equals 0; the lower 3 bytes, from least to most significant byte, determine the amount of red, green, and blue, respectively. The red, green, and blue components are each represented by a number between 0 and 255 (&HFF). If the high byte isn't 0, Visual Basic uses the system colors, as defined in the user's Control Panel settings and by constants listed in the Visual Basic (VB) object library in the Object Browser.

Note This property has no effect on the display of an image unless the Picture property of the CoolBar control contains a valid image and the EmbossPicture property is set to True.


EmbossPicture Property

Returns or sets a value indicating whether the background picture on a CoolBar control will be displayed in two colors or multiple colors.

Syntax

object.EmbossPicture [= boolean]

The EmbossPicture property syntax has these parts:

Part | Description
object | An object expression that evaluates to a CoolBar control.
boolean | A Boolean expression specifying whether the background picture is displayed in two colors or in multiple colors.

Settings

The settings for boolean are:

Setting | Description
False | (Default) Background picture is displayed in multiple colors.
True | Background picture is displayed in two colors.

Remarks

By default, the background picture on a CoolBar control will be displayed using the colors contained in the image file assigned to the Picture property. When the EmbossPicture property is True, the background picture will be dithered to the two colors specified in the EmbossHighlight and EmbossShadow properties.

Note This property has no effect unless the Picture property of the CoolBar control contains a valid image. If the UseCoolbarPicture property of a contained Band object is set to False, this property has no effect on that Band.


EmbossShadow Property

Sets or returns the shadow color for an image displayed on a CoolBar control.

Syntax

object.EmbossShadow [= color]

The EmbossShadow property syntax has these parts:

Part | Description
object | An object expression that evaluates to a CoolBar control.
color | A value or constant that determines the background or foreground colors of an object, as described in Settings.

Settings

Visual Basic uses the Microsoft Windows operating environment red-green-blue (RGB) color scheme. The settings for color are:

Setting | Description
Normal RGB colors | Colors specified by using the Color palette or by using the RGB or QBColor functions in code.
System default colors | Colors specified by system color constants listed in the Visual Basic (VB) object library in the Object Browser. The Windows operating environment substitutes the user's choices as specified in the Control Panel settings.

Remarks

The default setting for the EmbossShadow property is the system default color specified by the constant vbButtonFace.

The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a number in this range equals 0; the lower 3 bytes, from least to most significant byte, determine the amount of red, green, and blue, respectively. The red, green, and blue components are each represented by a number between 0 and 255 (&HFF). If the high byte isn't 0, Visual Basic uses the system colors, as defined in the user's Control Panel settings and by constants listed in the Visual Basic (VB) object library in the Object Browser.

Note This property has no effect on the display of an image unless the Picture property of the CoolBar control contains a valid image and the EmbossPicture property is set to True.


FixedBackground Property (Band Object)

Returns or sets a value indicating whether the background picture on a CoolBar control remains fixed when bands are rearranged.

Syntax

object.FixedBackground [= boolean]

The FixedBackGround property syntax has these parts:

Part | Description
object | An object expression that evaluates to a Band object.
boolean | A Boolean expression specifying whether the background picture is fixed or movable.

Settings

The settings for boolean are:

Setting | Description
True | (Default) Background picture is fixed.
False | Background picture is not fixed.

Remarks

The default behavior for the Picture property of a CoolBar control is to display the picture tiled across all bands on the control, using the Top and Left of the CoolBar control as the origin. If the bands are rearranged or resized, the picture is redrawn across all bands.

When the FixedBackground property is set to False, the picture is tiled within each band on the control. If the bands are rearranged or resized, the picture remains fixed within each band.

Note This property only applies to the Picture property of the CoolBar itself. If a picture is assigned to the Picture property of a Band object and the UseCoolBarPicture property for that band is set to False, the FixedBackground property has no effect on that band.


FixedOrder Property

Returns or sets a value indicating whether the user is allowed to rearrange the order of the bands on a CoolBar control at run time.

Syntax

object.FixedOrder [= boolean]

The FixedOrder property syntax has these parts:

Part | Description
object | An object expression that evaluates to a CoolBar control.
boolean | A Boolean expression specifying whether the band is visible or hidden.

Settings

The settings for boolean are:

Setting | Description
False | (Default) Bands can be rearranged.
True | Bands cannot be rearranged.

Remarks

To fix the arrangement of bands on a CoolBar control, set the FixedOrder property to True at design time. This will prevent the user from rearranging the bands using drag and drop. Setting this property in code enables you to disable or enable the ability to rearrange bands at run time in response to a particular event. Setting this property affects all bands contained in a CoolBar control.


Image Property (Band Object)

Returns or sets a value that specifies which ListImage object in an ImageList control will appear on a Band object of a CoolBar control.

Syntax

object.Image [= index]

The Image property syntax has these parts:

Part | Description
object | An object expression that evaluates to a Band object.
index | An integer or unique string specifying the ListImage object to use with object. The integer is the value of the Index property, the string is the value of the Key property.

Remarks

Before setting the Image property, you must associate an ImageList control with the CoolBar control by setting the CoolBar’s ImageList property to an ImageList control.

At run time, the image contained in the ListImage object specified in the Image property will be displayed on the Band object between the move handle and the caption. The image is not displayed at design time.


MinHeight, MinWidth Properties (Band Object)

Returns or sets a value indicating the minimum height or width to which a Band object may be resized.

Syntax

object.MinHeight [= single]

object.MinWidth [= single]

The MinHeight and MinWidth property syntax has these parts:

Part | Description
object | An object expression that evaluates to a Band object.
single | A single-precision floating-point value indicating height or width.

Remarks

The default MinHeight value is equal to the Height of the Band object’s child control. You can set MinHeight to a greater value, but you can’t resize the Band below the default value.

Note When the Orientation of the CoolBar is set to vertical, the MinHeight becomes the MinWidth and the MinWidth becomes the MinHeight.


NewRow Property

Sets or returns whether a Band object will be displayed in a new row on the CoolBar control.

Syntax

object.NewRow [= boolean]

The NewRow property syntax has these parts:

Part | Description
object | An object expression that evaluates to a Band object.
boolean | A Boolean expression specifying whether the band will be displayed in a new row.

Settings

The settings for boolean are:

Setting | Description
False | (Default) Band will be added to the last existing row.
True | Band will start a new row.

Note The NewRow property doesn’t affect the first Band object in a Bands collection. The first Band always starts a new row.


Orientation Property (Coolbar Control)

Sets a value indicating whether the CoolBar control is oriented horizontally or vertically.

Syntax

object.Orientation [= enum]

The Orientation property syntax has these parts:

Part | Description
object | An object expression that evaluates to a CoolBar control.
enum | A constant or value specifying the orientation, as described in Settings.

Settings

The settings for enum are:

Constant | Value | Description
cc3OrientationHorizontal | 0 | (Default) Horizontal orientation.
cc3OrientationVertical | 1 | Vertical orientation.


Picture Property (Coolbar Control)

Returns or sets a graphic to be displayed in a control.

Syntax

object.Picture = LoadPicture(pathname)

object.Picture [= picture]

The Picture property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
pathname | A string expression specifying the path and filename of the file containing a graphic, as described in Settings.
picture | The Picture property of a Form object, PictureBox control, or Image control.

Settings

The settings for picture are:

Setting | Description
(None) | (Default) No picture.
(Bitmap, GIF, JPEG) | Specifies a graphic. You can load a graphic from the Property Page at design time. At run time, you can also set this property using the LoadPicture function.

Remarks

The Picture property of the CoolBar control displays a background graphic across all bands on the CoolBar, behind any child controls. Each Band object on a CoolBar control also has a Picture property and a UseCoolBarPicture property which can be used to override the Picture property of the control.


Position Property (Band Object)

Returns the position of a Band object within a CoolBar control.

Syntax

object.Position [= integer]

The Position property syntax has these parts:

Part | Description
object | An object expression that evaluates to a Band object.
integer | An integer indicating the current position.

Remarks

The Position property can be used to determine the current location of a Band within a CoolBar control. While the Index of a Band remains constant, the Position changes as the bands are rearranged.

The Position property begins with a value of 1 for the Band in the upper left position and increments from left to right, top to bottom when the CoolBar orientation is horizontal. When the orientation is vertical, Position increments top to bottom, left to right.


RowCount Property (Coolbar Control)

Returns the number of rows displayed in a CoolBar control.

Syntax

object.RowCount [= number]

The RowCount property syntax has these parts:

Part | Description
object | An object expression that evaluates to a CoolBar control.
number | A long integer indicating the number of rows.

Remarks

The number of rows displayed by a CoolBar control isn’t necessarily the same as the number of bands, since more than one band can be displayed in a single row.


Style Property (Band Object)

Sets or returns a value indicating the sizing behavior of a Band object in a CoolBar control.

Syntax

object.Style [= enum]

The Style property syntax has these parts:

Part | Description
object | An object expression that evaluates to a Band object.
enum | A constant or value specifying the style, as described in Settings.

Settings

The settings for enum are:

Constant | Value | Description
cc3BandNormal | 0 | (Default) Band can be resized. Sizing gripper is displayed only if there are two or more bands in the CoolBar control
cc3BandFixedSize | 1 | Band can not be resized. Sizing gripper is not displayed.


UseCoolbarColors Property

Sets or returns whether a Band object will use the CoolBar control’s ForeColor and BackColor properties.

Syntax

object.UseCoolbarColors [= boolean]

The UseCoolbarColors property syntax has these parts:

Part | Description
object | An object expression that evaluates to a Band object.
boolean | A Boolean expression specifying whether the band will override the CoolBar control’s ForeColor and BackColor.

Settings

The settings for boolean are:

Setting | Description
True | (Default) Band will display using the CoolBar control’s ForeColor and BackColor properties.
False | Band will display using its own ForeColor and BackColor properties.


UseCoolbarPicture Property

Sets or returns whether a Band object will use the CoolBar control’s Picture property.

Syntax

object.UseCoolbarPicture [= boolean]

The UseCoolbarPicture property syntax has these parts:

Part | Description
object | An object expression that evaluates to a Band object.
boolean | A Boolean expression specifying whether the band’s Picture property will override the CoolBar control’s Picture.

Settings

The settings for boolean are:

Setting | Description
True | (Default) Band will display the CoolBar control’s Picture.
False | Band will display its own Picture.


VariantHeight Property

Returns or sets a value indicating whether a CoolBar control displays all bands using the same height.

Syntax

object.VariantHeight [= boolean]

The VariantHeight property syntax has these parts:

Part | Description
object | An object expression that evaluates to a CoolBar control.
boolean | A Boolean expression specifying whether all bands are a uniform height.

Settings

The settings for boolean are:

Setting | Description
True | (Default) Band heights may vary.
False | Band heights are equal.

Remarks

When this property is set to False, the CoolBar control will display all bands based on the largest MinHeight property of all visible bands. When this property is set to True, the height of each band is based on its own MinHeight property if there is a single band in the row. If there is more than one band in a row, the bands will be displayed using the largest MinHeight property of all visible bands in that row.